---
title: smart-socket 文档写作标准
description: 为确保 smart-socket 文档的一致性、专业性和易读性而制定的写作标准。所有参与 smart-socket 文档编写的 AI 应遵循这些准则，以产出符合项目要求的高质量文档。
---

## 关于文档

本文档是 smart-socket 框架的文档写作标准指南，旨在确保所有 AI 生成的文档具有一致性、专业性和易读性。

smart-socket 文档遵循"实践为主，原理为辅"的理念，优先介绍功能的实际应用，然后根据需要解释相关技术原理，帮助读者快速上手并解决实际问题。

## 1. 文档结构规范

### 1.1 基本结构

一篇标准的 smart-socket 技术文档应包含以下要素：

1. **文档头部信息**：包含标题、描述等元数据
2. **引言部分**：简要介绍文档主题和目标
3. **主体内容**：按逻辑顺序组织的技术内容
4. **总结部分**：概括要点或提供进一步学习指引
5. **参考资料**：相关链接和扩展阅读

### 1.2 文档头部信息

每篇文档必须包含标准的头部信息（Frontmatter）：

```md
---
title: 文档标题
description: 简短描述文档内容
sidebar:
  order: 排序数字（可选）
---
```

### 1.3 标题层级规范

- 由于已存在文章title，无需使用 `#` 表示主标题（H1）
- 使用 `##` 表示章节标题（H2）
- 使用 `###` 表示小节标题（H3）
- 最多使用三级标题，避免更深的嵌套

### 1.4 内容组织原则

1. **实践优先**：优先介绍如何使用功能，提供实际可用的示例
2. **原理补充**：在读者了解基本用法后，适当解释背后的原理
3. **循序渐进**：从基础功能开始，逐步深入高级特性
4. **实例驱动**：通过具体示例演示功能的使用方法

## 2. 语言风格标准

### 2.1 语言风格要求

为了使文档更具亲和力和可读性，应遵循以下语言风格要求：

- 使用亲切自然的语调，就像技术专家在与读者面对面交流
- 避免机械生硬、缺乏情感的表达，适当使用生活化、具象化的词汇
- 在恰当处融入轻松语气，但不影响技术内容的严谨性

### 2.2 叙述方式

采用以下叙述方式可以提高文档的可读性：

- 采用引导式叙述，如"让我们一起来实现一个简单的HTTP服务器"
- 善用设问句引发读者思考，如"你是否想过这个功能是如何实现的？"
- 适当使用修辞手法，让抽象的技术概念更易于理解

### 2.3 情感表达

适当的情感表达可以增强读者的阅读体验：

- 在适当时机表达对技术的热情，如"这个特性真是太棒了"
- 对于复杂概念给予读者鼓励，如"别担心，我们一起慢慢来"
- 体现对读者学习进度的关心，如"掌握了这些基础，你就能轻松应对大部分场景了"

### 2.4 互动性增强

增强文档的互动性有助于提高读者参与度：

- 多使用"我们"、"你"等人称代词，营造共同学习的氛围
- 在关键知识点处设置提醒，如"这里有个小细节需要注意"
- 在段落结尾适当提出启发性问题，激发读者思考

## 3. 技术内容标准

### 3.1 代码示例规范

代码示例是技术文档的重要组成部分，应遵循以下规范：

- 每段代码示例必须配有简要说明，重点说明用途和使用方法
- 重要的代码行应添加注释，特别是关键参数和配置项
- 示例代码应具备完整性和可执行性
- **突出实践**：优先展示功能的具体应用场景，而非理论框架
- **简化示例**：仅展示与当前讨论主题相关的核心代码，避免冗长的样板代码
- 使用适当的语法高亮标记
- **代码验证**：所有代码示例必须基于项目实际源码，确保与项目实际情况完全一致，不得出现任何虚构或不正确的代码片段

所有代码示例都应该链接到 Gitee 仓库中的实际文件，以便读者可以查看完整的上下文和运行示例。
:::note
如果文档中的代码示例需要提供完整可运行的代码，应当在文档中添加指向 Gitee 仓库中实际文件的链接，方便读者查找和运行完整示例。
代码统一存放在：https://gitee.com/smartboot/smart-socket/blob/master/example/src/main/javajava/org/smartboot/socket/example/ 目录下。
:::

:::caution
强制要求：所有文档中的代码示例必须经过严格验证，确保与项目实际代码保持完全一致。AI在编写文档时必须参考项目真实存在的源码文件，禁止生成任何虚构或不正确的代码。所有链接必须指向 Gitee 仓库。
:::

### 3.2 功能实践与原理解析

在文档编写过程中，应按照以下方式平衡功能实践和原理解析：

**实践优先原则**：
- 首先介绍功能的作用和使用场景
- 提供可直接运行的代码示例
- 说明常见配置选项及其效果

**原理补充原则**：
- 在读者掌握基本用法后，适时解释工作原理
- 通过图表等方式直观展示内部机制
- 避免一开始就陷入复杂的理论讲解

**层次化内容组织**：
- 基础用法部分：专注于"怎么做"
- 进阶用法部分：解释"为什么这样做"
- 工作原理解析：深入探讨"它是如何工作的"

### 3.3 图表使用规范

- **首选 Mermaid**：对于流程图、架构图等，优先使用 Mermaid 语法
- **复杂图表使用通道图**：对于复杂的系统交互图、数据流图等，优先使用通道图进行表达
- 图表应有明确的标题和说明文字
- 图片文件应存储在相应的 img 目录中
- 使用相对路径引用图片
- 使用 Mermaid 时，必须在文档顶部导入自定义组件：`import Mermaid from '../../../components/Mermaid.astro';`

#### 3.3.1 Mermaid 图表规范

为了生成高质量的 Mermaid 图表，请遵循以下规范：

1. **图表结构要求**：
   - 使用清晰的节点命名，避免使用无意义的字母
   - 节点文本应简洁明了，不超过一行
   - 连接线应有明确含义，必要时添加标签
   - 保持图表布局整洁，避免线条交叉

2. **图表类型选择**：
   - 流程图：`graph TD` 或 `graph LR` 用于表示执行流程
   - 序列图：`sequenceDiagram` 用于表示对象间交互
   - 类图：`classDiagram` 用于表示类关系
   - 状态图：`stateDiagram` 用于表示状态变化
   - 组件图：`graph TD` 用于表示系统组件关系

3. **节点样式规范**：
   - 方形节点：`A[节点文本]`
   - 圆形节点：`A((节点文本))`
   - 菱形节点：`A{条件判断}`
   - 圆角矩形：`A(节点文本)`

4. **图表设计原则**：
   - **一致性**：同一文档中相同类型的元素应使用相同的样式
   - **可读性**：确保节点文本清晰可见，避免过长文本
   - **逻辑性**：图表流向应符合常规阅读习惯（从上到下或从左到右）
   - **简洁性**：只包含必要的信息，避免图表过于复杂

5. **Mermaid 图表样式风格约束**：

为了确保 smart-socket 文档中所有 Mermaid 图表具有一致的视觉风格和专业外观，特制定以下样式约束：

**颜色规范**：
   - 默认使用黑白配色方案，确保打印和屏幕显示效果一致
   - 如需使用颜色，应遵循 smart-socket 品牌色彩规范：主色调为蓝色 (#2196F3)
   - 不同类型的节点应通过形状区分，而非颜色区分
   - 连接线使用黑色，默认宽度为 1px

**字体规范**：
   - 节点文本使用与文档正文一致的字体
   - 字号应适中，确保在不同设备上都能清晰阅读
   - 避免使用特殊字体效果（如斜体、下划线等）
   - 文本对齐方式统一采用居中对齐

**间距与布局规范**：
   - 节点之间应保持适当间距，避免过于拥挤或分散
   - 图表整体应居中布局，避免偏向一侧
   - 连接线应尽量保持直线，避免不必要的弯曲
   - 当无法避免连线交叉时，应使用桥接符号明确表示

**响应式设计规范**：
   - 图表应能在不同屏幕尺寸下正常显示
   - 避免创建过大的图表，单个图表宽度不应超过 800px
   - 对于复杂图表，应考虑拆分为多个子图表
   - 移动端显示时，图表应能自适应缩放

6. **高质量示例**：

流程图示例：
```jsx
<Mermaid code={`
graph TD
    A[用户请求] --> B{身份验证}
    B -->|验证成功| C[处理请求]
    B -->|验证失败| D[返回错误]
    C --> E[返回结果]
    D --> E
`} />
```

序列图示例：
```jsx
<Mermaid code={`
sequenceDiagram
    participant U as 用户
    participant S as 服务器
    participant D as 数据库
    
    U->>S: 登录请求
    S->>D: 验证凭据
    D-->>S: 验证结果
    S-->>U: 登录响应
`} />
```

类图示例：
```jsx
<Mermaid code={`
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    
    class Dog {
        +String breed
        +bark()
    }
    
    class Cat {
        +String color
        +meow()
    }
    
    Animal <|-- Dog
    Animal <|-- Cat
`} />
```

组件图示例：
```jsx
<Mermaid code={`
graph TD
    A[客户端] --> B(负载均衡器)
    B --> C[Web服务器1]
    B --> D[Web服务器2]
    B --> E[Web服务器3]
    C --> F[(数据库)]
    D --> F
    E --> F
`} />
```

在使用 Mermaid 图表之前，需要在文档顶部导入自定义的 Mermaid 组件：

```md
import Mermaid from '../../../components/Mermaid.astro';
```

然后在文档正文中使用 Mermaid 组件：

```jsx
<Mermaid code={`
graph TD
    A[开始] --> B[处理]
    B --> C[结束]
`} />
```

#### 3.3.2 通道图使用规范

对于复杂的系统架构图、数据流图等，应优先考虑使用通道图（Channel Diagram）：

1. **适用场景**：
   - 复杂的系统交互图
   - 多组件数据流图
   - 高并发处理流程图
   - 网络通信架构图

2. **设计原则**：
   - 清晰表达数据流向和处理节点
   - 合理划分通道和处理单元
   - 保持整体结构简洁易懂

3. **示例**：
```jsx
<Mermaid code={`
graph LR
    A[数据源] --> B{通道1}
    B --> C[处理器1]
    C --> D{通道2}
    D --> E[处理器2]
    E --> F[结果输出]
`} />
```

#### 3.3.3 架构设计图要求

对于相对复杂的功能，必须提供架构设计图，以便读者更好地理解系统的整体结构和各组件之间的关系：

1. **架构图内容要求**：
   - 展示系统的核心组件
   - 明确组件间的依赖关系
   - 标注数据流向
   - 说明关键接口和协议

2. **架构图绘制规范**：
   - 使用标准的图形符号（矩形表示组件，箭头表示关系）
   - 保持布局清晰，避免线条交叉
   - 添加必要的文字说明和图例
   - 为复杂系统提供分层视图

3. **架构图示例**：
```jsx
<Mermaid code={`
graph TB
    A[客户端] --> B[API网关]
    B --> C[认证服务]
    B --> D[业务服务]
    B --> E[数据存储]
    C --> F[(用户数据库)]
    D --> F
    D --> G[(业务数据库)]
`} />
```

## 4. 格式排版规范

### 4.1 强调样式

- **加粗**：用于强调关键词或重要概念
- *斜体*：用于首次提及的术语或书籍名称
- `代码`：用于行内代码或命令，注意格式正确性:"```"

### 4.2 列表使用

- 有序列表用于步骤说明
- 无序列表用于列举要点
- 列表项应保持平行结构

### 4.3 表格规范

- 表头使用简洁明确的标签
- 表格内容应左对齐
- 表格前后应有说明文字

## 5. 特殊内容处理

### 5.1 注意事项与警告

对于需要特别提醒的内容，使用专门的提示框：

:::note
这是一般性提示信息
:::

:::caution
这是需要注意的警告信息
:::

:::tip
这是技巧或建议信息
:::

:::danger
这是危险或重要警告信息
:::

## 6. AI 写作指导原则

为确保 AI 生成的文档既专业又具有良好的可读性，需要遵循以下指导原则：

### 6.1 内容准确性

- 确保功能使用说明的准确性
- 基于 smart-socket 项目实际情况进行描述
- 优先验证实践示例的正确性
- 避免推测性内容
- 所有代码示例必须与项目实际源码保持一致，禁止虚构代码

### 6.2 写作规范

- 严格遵循本文档规定的格式和风格
- 保持语言表达的一致性
- 确保文档结构清晰

### 6.3 上下文理解

- 准确理解用户查询意图，重点关注功能使用需求
- 结合 smart-socket 框架特点进行阐述，突出实用性
- 考虑目标读者的技术水平，提供合适的实践指导

## 7. 文档质量检查清单

在完成文档编写后，请对照以下清单进行检查：

- [ ] 标题是否准确反映内容主旨
- [ ] 是否优先介绍了功能的使用方法
- [ ] 是否提供了实际可用的代码示例
- [ ] 是否在适当时机解释了相关原理
- [ ] 代码示例是否完整且可运行
- [ ] 代码示例是否与项目实际源码一致
- [ ] 是否引用了实际存在的源码文件
- [ ] 是否存在错别字或语法错误
- [ ] 链接是否有效且指向 Gitee 仓库
- [ ] 图片是否正常显示
- [ ] 内容是否有逻辑错误或表述不清之处
- [ ] 是否符合整体文档风格
- [ ] 是否遵循了所有格式和结构标准
- [ ] 各章节是否逻辑清晰、粒度适中
- [ ] 对于复杂功能是否提供了架构设计图

通过遵循以上标准，AI 编写的 smart-socket 文档将更加专业、一致且易于理解，有助于提升整个项目的文档质量和用户体验。

## 8. 总结

本文档为 smart-socket 框架的 AI 文档生成提供了全面的指导原则。通过遵循这些规范，AI 可以生成高质量、一致性强且易于理解的技术文档。记住始终以用户需求为中心，注重实用性，并保持内容的准确性和时效性。